3D Graphics Programming with QuickDraw 3D 1.5.4

Tags for State Variables

A drawing engine maintains a large number of state variables that determine how the engine draws into a device. Each state variable has a state value, which is either an unsigned long integer, a floating-point value, or a pointer. You can read and write state values by calling QuickDraw 3D RAVE functions. (For instance, you can set a state value by calling QASetInt , QASetFloat , or QASetPtr .) You specify which state variable to get or set using a state tag, a unique identifier associated with that variable.

All tag values greater than 0 and less than kQATag_EngineSpecific_Minimum are reserved for use by QuickDraw 3D RAVE. If you need to define engine-specific tags, you should assign them tag values greater than or equal to kQATag_EngineSpecific_Minimum .

Here are the tags for state variables having unsigned long integer values:



 
typedef enum TQATagInt {

    kQATag_ZFunction                    = 0,    /*required variables*/

    kQATag_Antialias                    = 8,    /*optional variables*/

    kQATag_Blend                        = 9,

    kQATag_PerspectiveZ                 = 10,

    kQATag_TextureFilter                = 11,

    kQATag_TextureOp                    = 12,

    kQATag_CSGTag                       = 14,

    kQATag_CSGEquation                  = 15,

    kQATag_BufferComposite              = 16,

    kQATagGL_DrawBuffer                 = 100,  /*OpenGL variables*/

    kQATagGL_TextureWrapU               = 101,

    kQATagGL_TextureWrapV               = 102,

    kQATagGL_TextureMagFilter           = 103,

    kQATagGL_TextureMinFilter           = 104,

    kQATagGL_ScissorXMin                = 105,

    kQATagGL_ScissorYMin                = 106,

    kQATagGL_ScissorXMax                = 107,

    kQATagGL_ScissorYMax                = 108,

    kQATagGL_BlendSrc                   = 109,

    kQATagGL_BlendDst                   = 110,

    kQATagGL_LinePattern                = 111,

    kQATagGL_AreaPattern0               = 117,

    kQATagGL_AreaPattern31              = 148,

    kQATag_EngineSpecific_Minimum       = 1000

} TQATagInt;

Constant descriptions

kQATag_ZFunction: The z sorting function of the drawing engine. This function determines which surfaces are to be removed during hidden surface removal. See "Z Sorting Function Selectors" for a description of the available z sorting functions. The default value for a drawing engine that is z buffered is kQAZFunction_LT ; the default value for a draw context that is not z buffered is kQAZFunction_None . The z sorting function state variable must be supported by all drawing engines.
kQATag_Antialias: The antialiasing mode of the drawing engine. This mode determines how, if at all, antialiasing is applied to the draw context. See "Antialiasing Selectors" for a description of the available antialiasing modes. The default value for a drawing engine that supports antialiasing is kQAAntiAlias_Fast . The antialiasing mode state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_Antialias feature.
kQATag_Blend: The transparency blending function of the drawing engine. See "Blending Operations" for a description of the available transparency blending functions. The default value for a drawing engine that supports blending is kQABlend_Premultiply . The transparency blending function state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_Blend feature.
kQATag_PerspectiveZ: The z perspective control of the drawing engine. This control determines how a drawing engine performs hidden surface removal. See "Z Perspective Selectors" for a description of the available z perspective controls. The default value for a drawing engine that supports z perspective is kQAPerspectiveZ_Off . The z perspective control state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_PerspectiveZ feature.
kQATag_TextureFilter: The texture mapping filter mode of the drawing engine. This mode determines how a drawing engine performs texture mapping. See "Texture Filter Selectors" for a description of the available texture mapping filter modes. The default value for a drawing engine that supports texture mapping is kQATextureFilter_Fast . The texture mapping filter state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_Texture feature.
kQATag_TextureOp: The texture mapping operation of the drawing engine. This mode determines the current texture mapping operation of a drawing engine. See "Texture Operations" for a description of the available texture mapping operations. The default value for a drawing engine that supports texture mapping is kQATextureOp_None . The texture mapping operation variable is optional; it must be supported only when a drawing engine supports the kQAOptional_Texture feature.
kQATag_CSGTag: The CSG ID of triangles subsequently submitted to the drawing engine. See "CSG IDs" for a description of the available CSG IDs. The default value for a drawing engine that supports CSG operations is kQACSGTag_None . The CSG ID variable is optional; it must be supported only when a drawing engine supports the kQAOptional_CSG feature.
kQATag_CSGEquation: The CSG equation for the drawing engine, which determines the manner in which triangles with CSG IDs are combined into solid objects. See the book 3D Graphics Programming With QuickDraw 3D for an explanation of how to specify a CSG equation. The CSG equation variable is optional; it must be supported only when a drawing engine supports the kQAOptional_CSG feature.
kQATag_BufferComposite: The buffer compositing mode of the drawing engine. This mode determines how a drawing engine composites generated pixels with the initial contents of the drawing buffer. See "Buffer Compositing Modes" for a description of the available buffer compositing modes. The default value for a drawing engine that supports buffer compositing is kQABufferComposite_None . The buffer compositing state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_BufferComposite feature.
kQATagGL_DrawBuffer: The OpenGL color buffer of the drawing engine. This determines where a drawing engine draws when writing colors to a frame buffer. See "Buffer Drawing Operations" for a description of the buffer drawing modes. The default value of this variable for a drawing engine that supports OpenGL buffering is kQAGL_DrawBuffer_Front for single-buffered contexts and kQAGL_DrawBuffer_Back for double-buffered contexts. The OpenGL color buffer state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_OpenGL feature.
kQATagGL_TextureWrapU: The OpenGL texture u wrapping mode of the drawing engine. See "Texture Wrapping Values" for a description of the wrapping modes. The default value of this variable for a drawing engine that supports OpenGL texture wrapping is kQAGL_Repeat . The OpenGL texture u wrapping mode state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_OpenGL feature.
kQATagGL_TextureWrapV: The OpenGL texture v wrapping mode of the drawing engine. See "Texture Wrapping Values" for a description of the wrapping modes. The default value of this variable for a drawing engine that supports OpenGL texture wrapping is kQAGL_Repeat . The OpenGL texture v wrapping mode state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_OpenGL feature.
kQATagGL_TextureMagFilter: The OpenGL texture magnification function of the drawing engine. This function is called when a pixel being textured maps to an area that is less than or equal to one texture element. The default value of this variable for a drawing engine that supports OpenGL texture magnification is kQAGL_Linear . The OpenGL texture magnification function state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_OpenGL feature.
kQATagGL_TextureMinFilter: The OpenGL texture minifying function of the drawing engine. This function is called when a pixel being textured maps to an area that is greater than one texture element. See [to be supplied] for a description of the available minifying functions. The default value of this variable for a drawing engine that supports OpenGL texture minifying is kQAGL_ToBeSupplied . The OpenGL texture minifying function state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_OpenGL feature.
kQATagGL_ScissorXMin: The minimum x value of the scissor box, a rectangle that determines which pixels can be modified by drawing commands. This state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_OpenGL feature.
kQATagGL_ScissorYMin: The minimum y value of the scissor box. This state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_OpenGL feature.
kQATagGL_ScissorXMax: The maximum x value of the scissor box. This state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_OpenGL feature.
kQATagGL_ScissorYMax: The maximum y value of the scissor box. This state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_OpenGL feature.
kQATagGL_BlendSrc: The source blending operation of the drawing engine. This control determines how a drawing engine computes the; red, green, blue, and alpha source-blending factors when performing transparency blending. The source blending operation state variable is optional; it must be supported only when a drawing engine supports both the kQAOptional_Blend and kQAOptional_OpenGL features.
kQATagGL_BlendDst: The destination blending operation of the drawing engine. This control determines how a drawing engine computes the red, green, blue, and alpha destination-blending factors when performing transparency blending. The destination blending operation state variable is optional; it must be supported only when a drawing engine supports both the kQAOptional_Blend and kQAOptional_OpenGL features.
kQATagGL_LinePattern: The OpenGL line stipple pattern of the drawing engine. This pattern specifies which bits in a line are to be drawn and which are masked out.
kQATagGL_AreaPattern0: The first of 32 registers that specify an area stipple pattern.
kQATagGL_AreaPattern31: The last of 32 area stipple pattern registers.
kQATag_EngineSpecific_Minimum: The minimum tag value to be used for variables that are specific to a particular drawing engine. Any custom variables you support must have tag values greater than or equal to this value. Note that you should use engine-specific tags only in exceptional circumstances, because the operations determined by the associated state variables are not generally accessible.

Here are the tags for state variables having floating-point values:



 
typedef enum TQATagFloat {

    kQATag_ColorBG_a                    = 1,    /*required variables*/

    kQATag_ColorBG_r                    = 2,

    kQATag_ColorBG_g                    = 3,

    kQATag_ColorBG_b                    = 4,

    kQATag_Width                        = 5,

    kQATag_ZMinOffset                   = 6,

    kQATag_ZMinScale                    = 7,

    kQATagGL_DepthBG                    = 112,  /*OpenGL variables*/

    kQATagGL_TextureBorder_a            = 113,

    kQATagGL_TextureBorder_r            = 114,

    kQATagGL_TextureBorder_g            = 115,

    kQATagGL_TextureBorder_b            = 116

} TQATagFloat;

Constant descriptions

kQATag_ColorBG_a: The alpha channel value of a drawing engine's background color. This value must be greater than or equal to 0.0 and less than or equal to 1.0. The default value for the background color alpha channel is 0.0. The background color alpha channel state variable must be supported by all drawing engines.
kQATag_ColorBG_r: The red component of a drawing engine's background color. This value must be greater than or equal to 0.0 and less than or equal to 1.0. The default value for the background color red component is 0.0. The background color red component state variable must be supported by all drawing engines.
kQATag_ColorBG_g: The green component of a drawing engine's background color. This value must be greater than or equal to 0.0 and less than or equal to 1.0. The default value for the background color green component is 0.0. The background color green component state variable must be supported by all drawing engines.
kQATag_ColorBG_b: The blue component of a drawing engine's background color. This value must be greater than or equal to 0.0 and less than or equal to 1.0. The default value for the background color blue component is 0.0. The background color blue component state variable must be supported by all drawing engines.
kQATag_Width: The width (in pixels) of points or lines drawn by the drawing engine. This value must be greater than or equal to 0.0 and less than or equal to kQAMaxWidth (currently defined as 128.0). The default value for the width is 1.0. The width state variable must be supported by all drawing engines.
kQATag_ZMinOffset: The minimum z offset that must be performed to guarantee that a drawn object passes the kQAZFunction_LT hidden surface test. This variable is read-only; you cannot set its value. In general, a drawing engine that employs fixed-point values for the z coordinate returns a small negative value (for example, -1/65536) for the minimum offset; a drawing engine that employs floating-point values for the z coordinate returns 0.0 for the minimum offset.
kQATag_ZMinScale: The minimum z scale factor that must be applied to guarantee that a drawn object passes the kQAZFunction_LT hidden surface test. This variable is read-only; you cannot set its value. In general, a drawing engine that employs fixed-point values for the z coordinate returns 1.0 for the minimum scale factor; a drawing engine that employs floating-point values for the z coordinate returns a value slightly less than 1.0 (for example, 0.9999) for the minimum scale factor.
kQATagGL_DepthBG: The OpenGL background z of the drawing engine. The default value of this variable for a drawing engine that supports OpenGL texture magnification is kQAGL_Linear . The OpenGL background z state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_OpenGL feature.
kQATagGL_TextureBorder_a: The alpha component of a drawing engine's texture border color. This value must be greater than or equal to 0.0 and less than or equal to 1.0. The default value for the texture border color alpha component is 0.0. The texture border color alpha component state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_OpenGL feature.
kQATagGL_TextureBorder_r: The red component of a drawing engine's texture border color. This value must be greater than or equal to 0.0 and less than or equal to 1.0. The default value for the texture border color red component is 0.0. The texture border color red component state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_OpenGL feature.
kQATagGL_TextureBorder_g: The green component of a drawing engine's texture border color. This value must be greater than or equal to 0.0 and less than or equal to 1.0. The default value for the texture border color green component is 0.0. The texture border color green component state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_OpenGL feature.
kQATagGL_TextureBorder_b: The blue component of a drawing engine's texture border color. This value must be greater than or equal to 0.0 and less than or equal to 1.0. The default value for the texture border color blue component is 0.0. The texture border color blue component state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_OpenGL feature.

Here are the tags for state variables having pointer values:



 
typedef enum TQATagPtr {

    kQATag_Texture                      = 13

} TQATagPtr;

Constant descriptions

kQATag_Texture: A pointer to the current texture map of the drawing engine, as created by the QATextureNew function. The default value for the texture map pointer is NULL . The texture map pointer state variable is optional; it must be supported only when a drawing engine supports the kQAOptional_Texture feature.